List Incidents

Route

/v2/incidents/list

Description

List and filter security incidents triggered by policy violations with advanced filtering, pagination, and optional AI summaries. Incidents represent security events that require investigation or response.

Method

POST

Inputs

Parameter	Type	Required	Description
page_request	PageRequest	No	Pagination and sorting configuration
page_request.size	integer	No	Number of results per page (max 1000)
page_request.id	string	No	Page token for next page
page_request.sort_by	string	No	Sort field and direction (e.g., "trigger_time desc")
filter	IncidentFilter	No	Filtering criteria
filter.policy_ids	array[string]	No	Specific policy IDs that triggered incidents
filter.policy_severities	array[string]	No	Policy severity levels (informational, low, medium, high, critical)
filter.dataset_ids	array[string]	No	Dataset IDs that were matched
filter.dataset_sensitivities	array[string]	No	Data sensitivity levels (unrestricted, low, moderate, high, critical)
filter.users	array[string]	No	Usernames who triggered incidents
filter.assignees	array[string]	No	Users assigned to incidents
filter.hostnames	array[string]	No	Endpoint hostnames where incidents occurred
filter.resolution_statuses	array[string]	No	Incident status (open, closed)
filter.start_time	string	No	Earliest incident time (ISO 8601 format)
filter.end_time	string	No	Latest incident time (ISO 8601 format)
include_ai_summaries	boolean	No	Include AI-generated incident summaries in response

Request Example

{
  "page_request": {
    "size": 50,
    "sort_by": "trigger_time desc"
  },
  "filter": {
    "policy_severities": ["high", "critical"],
    "resolution_statuses": ["open"],
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-31T23:59:59Z"
  },
  "include_ai_summaries": true
}

Output

Field	Type	Description
type	string	Always "incidents"
size	integer	Number of incidents returned
resources	array[Incident]	Array of incident objects
page_response	PageResponse	Pagination information
page_response.next_id	string	Token for next page
page_response.total	integer	Total number of matched incidents
errors	array[Error]	Any errors encountered

Incident Object Structure

Field	Type	Description
id	string	Unique incident identifier
trigger_time	string	When incident was triggered (ISO 8601)
event_time	string	When underlying event occurred (ISO 8601)
policy_id	string	Policy that triggered the incident
policy_name	string	Human-readable policy name
policy_severity	string	Policy severity level
user_id	string	User who triggered the incident
username	string	Username who triggered the incident
hostname	string	Endpoint hostname where incident occurred
event_lineage_ids	array[string]	Related event IDs for investigation
resolution_status	string	Current incident status
assignee	string	User assigned to incident
ai_summary	string	AI-generated incident summary (if requested)

Rate Limit

• 60 requests per minute per API key
• 5 concurrent requests per endpoint

Example Response

{
  "type": "incidents",
  "size": 1,
  "resources": [
    {
      "id": "incident-123",
      "trigger_time": "2024-01-15T10:30:00Z",
      "event_time": "2024-01-15T10:29:45Z",
      "policy_id": "policy-456",
      "policy_name": "Sensitive Data Upload Block",
      "policy_severity": "high",
      "user_id": "user-789",
      "username": "john.doe",
      "hostname": "LAPTOP-001",
      "event_lineage_ids": ["event-123", "event-124"],
      "resolution_status": "open",
      "assignee": "security.team",
      "ai_summary": "User attempted to upload sensitive customer data to external cloud storage. Action was blocked by policy."
    }
  ],
  "page_response": {
    "next_id": "eyJwYWdlX2lkIjoiMiJ9",
    "total": 25
  },
  "errors": []
}